<h2>DESCRIPTION</h2>

<p>The module fills a lake to a target water level from a given start point. The user
can think of it as <em><a href="r.grow">r.grow</a></em> with additional
checks for elevation. The resulting
raster map contains cells with values representing lake depth and NULL for all other 
cells beyond the lake. Lake depth is reported relative to specified water level
(specified level = 0 depth).

<p>This module uses a 3x3 moving window approach to find all cells that
match three criteria and to define the lake:

<ul>
 <li>cells are below the specified elevation (i.e., water level);</li>
 <li>cells are connected with an initial cell (seed or coordinates pair value);</li>
 <li>cells are not NULL or masked.</li>
</ul>

<p>The water level must be in DEM units.

<h2>NOTES</h2>

The seed (starting) point can be a raster map with at least one
cell value greater than zero, or a seed point can be specified as an E,
N coordinate pair. If the seed is specified as a coordinate pair, an additional
check is done to make sure that the target water level is above the level of 
the DEM. When a raster map is used as a seed, however, no such checks are done. 
Specifying a target water level below surface represented by DEM will result in an 
empty map. Note: a raster lake map created in a previous run can also be used
as a seed map for a new run to simulate rising water levels.

<p>
The module will create a new map (<b>lake=foo</b>) or can be set to replace
the input (<b>seed=bar</b>) map if the <b>-o</b> flag is used.  The user can use
<b>-o</b> flag to create animations of rising water level without
producing a separate map for each frame.  An initial seed map must be created 
to start the sequence, and will be overwritten during subsequent runs with resulting
water levels maps (i.e., a single file serves for both input and output).

<p>
Negative output (the <b>-n</b> flag) is useful for visualisations in NVIZ. 
It equals the mapcalc's expression <em>"negative = 0 - positive"</em>.

<h3>r.mapcalc equivalent - for GRASS hackers</h3>

This module was initially created as a script using
<em><a href="r.mapcalc">r.mapcalc</a></em>.
This had some limitations - it was slow and no
checks where done to find out required iteration count. The shell script 
code (using <em><a href="r.mapcalc">r.mapcalc</a></em>) used
in the original script is shown below:

<div class="code"><pre>
${seedmap} = if( ${dem}, \
if( if( isnull(${seedmap}),0,${seedmap}>0), ${wlevel}-${dem}, \
 if( \
  if(isnull(${seedmap}[-1,0]),0, ${seedmap}[-1,0]>0 && ${wlevel}>${dem}) ||\
  if(isnull(${seedmap}[-1,1]),0, ${seedmap}[-1,1]>0 && ${wlevel}>${dem}) ||\
  if(isnull(${seedmap}[0,1]), 0, ${seedmap}[0,1]>0  && ${wlevel}>${dem}) ||\
  if(isnull(${seedmap}[1,1]), 0, ${seedmap}[1,1]>0  && ${wlevel}>${dem}) ||\
  if(isnull(${seedmap}[1,0]), 0, ${seedmap}[1,0]>0  && ${wlevel}>${dem}) ||\
  if(isnull(${seedmap}[1,-1]),0, ${seedmap}[1,-1]>0 && ${wlevel}>${dem}) ||\
  if(isnull(${seedmap}[0,-1]),0, ${seedmap}[0,-1]>0 && ${wlevel}>${dem}) ||\
  if(isnull(${seedmap}[-1,-1]),0, ${seedmap}[-1,-1]>0 && ${wlevel}>${dem}),\
 ${wlevel}-${dem}, null() )))
</pre></div>

<p>
The <tt>${seedmap}</tt> variable is replaced by seed map names, <tt>${dem}</tt>
with DEM map name, and <tt>${wlevel}</tt> with target water level. To get
single water level, this code block is
called with same level numerous times (in a loop) as the lake grows by single cells
during single run.

<h2>KNOWN ISSUES</h2>

<ul>
  <li>The entire map is loaded into RAM.</li>
  <li>A completely negative seed map will not work! At least one cell must have 
    a value &gt; 0. Output from <tt>r.lake -n</tt> <em>cannot</em> be used
    as input in the next run.</li>
</ul>

<h2>EXAMPLE</h2>

Example of small flooding along a street (North Carolina sample dataset):

<div class="code"><pre>
g.region raster=elev_lid792_1m -p

# water accumulation next to street dam
r.lake elev_lid792_1m coordinates=638759.3,220264.1 water_level=113.4 lake=flooding

# draw resulting lake map over shaded terrain map
r.relief input=elev_lid792_1m output=elev_lid792_1m_shade
d.rast elev_lid792_1m_shade
d.rast flooding
d.vect streets_wake
</pre></div>

<p>
<center>
<img src="r_lake_lidar_dem.jpg" border=1><br>
Small flooding along a street (<em>r.lake</em>, using Lidar 1m DEM)
</center>

<h2>SEE ALSO</h2>

<em>
<a href="r.mapcalc.html">r.mapcalc</a>,
<a href="r.grow.html">r.grow</a>,
<a href="r.plane.html">r.plane</a>
</em>

<h2>AUTHOR</h2>
Maris Nartiss (maris.nartiss gmail.com)

<!--
<p>
<i>Last changed: $Date$</i>
-->
